home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / include / linux / firewire-cdev.h < prev    next >
Encoding:
C/C++ Source or Header  |  2009-09-09  |  17.4 KB  |  483 lines

  1. /*
  2.  * Char device interface.
  3.  *
  4.  * Copyright (C) 2005-2006  Kristian Hoegsberg <krh@bitplanet.net>
  5.  *
  6.  * This program is free software; you can redistribute it and/or modify
  7.  * it under the terms of the GNU General Public License as published by
  8.  * the Free Software Foundation; either version 2 of the License, or
  9.  * (at your option) any later version.
  10.  *
  11.  * This program is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with this program; if not, write to the Free Software Foundation,
  18.  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  19.  */
  20.  
  21. #ifndef _LINUX_FIREWIRE_CDEV_H
  22. #define _LINUX_FIREWIRE_CDEV_H
  23.  
  24. #include <linux/ioctl.h>
  25. #include <linux/types.h>
  26. #include <linux/firewire-constants.h>
  27.  
  28. #define FW_CDEV_EVENT_BUS_RESET        0x00
  29. #define FW_CDEV_EVENT_RESPONSE        0x01
  30. #define FW_CDEV_EVENT_REQUEST        0x02
  31. #define FW_CDEV_EVENT_ISO_INTERRUPT    0x03
  32.  
  33. /**
  34.  * struct fw_cdev_event_common - Common part of all fw_cdev_event_ types
  35.  * @closure:    For arbitrary use by userspace
  36.  * @type:    Discriminates the fw_cdev_event_ types
  37.  *
  38.  * This struct may be used to access generic members of all fw_cdev_event_
  39.  * types regardless of the specific type.
  40.  *
  41.  * Data passed in the @closure field for a request will be returned in the
  42.  * corresponding event.  It is big enough to hold a pointer on all platforms.
  43.  * The ioctl used to set @closure depends on the @type of event.
  44.  */
  45. struct fw_cdev_event_common {
  46.     __u64 closure;
  47.     __u32 type;
  48. };
  49.  
  50. /**
  51.  * struct fw_cdev_event_bus_reset - Sent when a bus reset occurred
  52.  * @closure:    See &fw_cdev_event_common; set by %FW_CDEV_IOC_GET_INFO ioctl
  53.  * @type:    See &fw_cdev_event_common; always %FW_CDEV_EVENT_BUS_RESET
  54.  * @node_id:       New node ID of this node
  55.  * @local_node_id: Node ID of the local node, i.e. of the controller
  56.  * @bm_node_id:    Node ID of the bus manager
  57.  * @irm_node_id:   Node ID of the iso resource manager
  58.  * @root_node_id:  Node ID of the root node
  59.  * @generation:    New bus generation
  60.  *
  61.  * This event is sent when the bus the device belongs to goes through a bus
  62.  * reset.  It provides information about the new bus configuration, such as
  63.  * new node ID for this device, new root ID, and others.
  64.  */
  65. struct fw_cdev_event_bus_reset {
  66.     __u64 closure;
  67.     __u32 type;
  68.     __u32 node_id;
  69.     __u32 local_node_id;
  70.     __u32 bm_node_id;
  71.     __u32 irm_node_id;
  72.     __u32 root_node_id;
  73.     __u32 generation;
  74. };
  75.  
  76. /**
  77.  * struct fw_cdev_event_response - Sent when a response packet was received
  78.  * @closure:    See &fw_cdev_event_common;
  79.  *        set by %FW_CDEV_IOC_SEND_REQUEST ioctl
  80.  * @type:    See &fw_cdev_event_common; always %FW_CDEV_EVENT_RESPONSE
  81.  * @rcode:    Response code returned by the remote node
  82.  * @length:    Data length, i.e. the response's payload size in bytes
  83.  * @data:    Payload data, if any
  84.  *
  85.  * This event is sent when the stack receives a response to an outgoing request
  86.  * sent by %FW_CDEV_IOC_SEND_REQUEST ioctl.  The payload data for responses
  87.  * carrying data (read and lock responses) follows immediately and can be
  88.  * accessed through the @data field.
  89.  */
  90. struct fw_cdev_event_response {
  91.     __u64 closure;
  92.     __u32 type;
  93.     __u32 rcode;
  94.     __u32 length;
  95.     __u32 data[0];
  96. };
  97.  
  98. /**
  99.  * struct fw_cdev_event_request - Sent on incoming request to an address region
  100.  * @closure:    See &fw_cdev_event_common; set by %FW_CDEV_IOC_ALLOCATE ioctl
  101.  * @type:    See &fw_cdev_event_common; always %FW_CDEV_EVENT_REQUEST
  102.  * @tcode:    Transaction code of the incoming request
  103.  * @offset:    The offset into the 48-bit per-node address space
  104.  * @handle:    Reference to the kernel-side pending request
  105.  * @length:    Data length, i.e. the request's payload size in bytes
  106.  * @data:    Incoming data, if any
  107.  *
  108.  * This event is sent when the stack receives an incoming request to an address
  109.  * region registered using the %FW_CDEV_IOC_ALLOCATE ioctl.  The request is
  110.  * guaranteed to be completely contained in the specified region.  Userspace is
  111.  * responsible for sending the response by %FW_CDEV_IOC_SEND_RESPONSE ioctl,
  112.  * using the same @handle.
  113.  *
  114.  * The payload data for requests carrying data (write and lock requests)
  115.  * follows immediately and can be accessed through the @data field.
  116.  */
  117. struct fw_cdev_event_request {
  118.     __u64 closure;
  119.     __u32 type;
  120.     __u32 tcode;
  121.     __u64 offset;
  122.     __u32 handle;
  123.     __u32 length;
  124.     __u32 data[0];
  125. };
  126.  
  127. /**
  128.  * struct fw_cdev_event_iso_interrupt - Sent when an iso packet was completed
  129.  * @closure:    See &fw_cdev_event_common;
  130.  *        set by %FW_CDEV_CREATE_ISO_CONTEXT ioctl
  131.  * @type:    See &fw_cdev_event_common; always %FW_CDEV_EVENT_ISO_INTERRUPT
  132.  * @cycle:    Cycle counter of the interrupt packet
  133.  * @header_length: Total length of following headers, in bytes
  134.  * @header:    Stripped headers, if any
  135.  *
  136.  * This event is sent when the controller has completed an &fw_cdev_iso_packet
  137.  * with the %FW_CDEV_ISO_INTERRUPT bit set.  In the receive case, the headers
  138.  * stripped of all packets up until and including the interrupt packet are
  139.  * returned in the @header field.
  140.  */
  141. struct fw_cdev_event_iso_interrupt {
  142.     __u64 closure;
  143.     __u32 type;
  144.     __u32 cycle;
  145.     __u32 header_length;
  146.     __u32 header[0];
  147. };
  148.  
  149. /**
  150.  * union fw_cdev_event - Convenience union of fw_cdev_event_ types
  151.  * @common:        Valid for all types
  152.  * @bus_reset:     Valid if @common.type == %FW_CDEV_EVENT_BUS_RESET
  153.  * @response:      Valid if @common.type == %FW_CDEV_EVENT_RESPONSE
  154.  * @request:       Valid if @common.type == %FW_CDEV_EVENT_REQUEST
  155.  * @iso_interrupt: Valid if @common.type == %FW_CDEV_EVENT_ISO_INTERRUPT
  156.  *
  157.  * Convenience union for userspace use.  Events could be read(2) into an
  158.  * appropriately aligned char buffer and then cast to this union for further
  159.  * processing.  Note that for a request, response or iso_interrupt event,
  160.  * the data[] or header[] may make the size of the full event larger than
  161.  * sizeof(union fw_cdev_event).  Also note that if you attempt to read(2)
  162.  * an event into a buffer that is not large enough for it, the data that does
  163.  * not fit will be discarded so that the next read(2) will return a new event.
  164.  */
  165. union fw_cdev_event {
  166.     struct fw_cdev_event_common common;
  167.     struct fw_cdev_event_bus_reset bus_reset;
  168.     struct fw_cdev_event_response response;
  169.     struct fw_cdev_event_request request;
  170.     struct fw_cdev_event_iso_interrupt iso_interrupt;
  171. };
  172.  
  173. #define FW_CDEV_IOC_GET_INFO        _IOWR('#', 0x00, struct fw_cdev_get_info)
  174. #define FW_CDEV_IOC_SEND_REQUEST    _IOW('#', 0x01, struct fw_cdev_send_request)
  175. #define FW_CDEV_IOC_ALLOCATE        _IOWR('#', 0x02, struct fw_cdev_allocate)
  176. #define FW_CDEV_IOC_DEALLOCATE        _IOW('#', 0x03, struct fw_cdev_deallocate)
  177. #define FW_CDEV_IOC_SEND_RESPONSE    _IOW('#', 0x04, struct fw_cdev_send_response)
  178. #define FW_CDEV_IOC_INITIATE_BUS_RESET    _IOW('#', 0x05, struct fw_cdev_initiate_bus_reset)
  179. #define FW_CDEV_IOC_ADD_DESCRIPTOR    _IOWR('#', 0x06, struct fw_cdev_add_descriptor)
  180. #define FW_CDEV_IOC_REMOVE_DESCRIPTOR    _IOW('#', 0x07, struct fw_cdev_remove_descriptor)
  181.  
  182. #define FW_CDEV_IOC_CREATE_ISO_CONTEXT    _IOWR('#', 0x08, struct fw_cdev_create_iso_context)
  183. #define FW_CDEV_IOC_QUEUE_ISO        _IOWR('#', 0x09, struct fw_cdev_queue_iso)
  184. #define FW_CDEV_IOC_START_ISO        _IOW('#', 0x0a, struct fw_cdev_start_iso)
  185. #define FW_CDEV_IOC_STOP_ISO        _IOW('#', 0x0b, struct fw_cdev_stop_iso)
  186. #define FW_CDEV_IOC_GET_CYCLE_TIMER    _IOR('#', 0x0c, struct fw_cdev_get_cycle_timer)
  187.  
  188. /* FW_CDEV_VERSION History
  189.  *
  190.  * 1    Feb 18, 2007:  Initial version.
  191.  */
  192. #define FW_CDEV_VERSION        1
  193.  
  194. /**
  195.  * struct fw_cdev_get_info - General purpose information ioctl
  196.  * @version:    The version field is just a running serial number.
  197.  *        We never break backwards compatibility, but may add more
  198.  *        structs and ioctls in later revisions.
  199.  * @rom_length:    If @rom is non-zero, at most rom_length bytes of configuration
  200.  *        ROM will be copied into that user space address.  In either
  201.  *        case, @rom_length is updated with the actual length of the
  202.  *        configuration ROM.
  203.  * @rom:    If non-zero, address of a buffer to be filled by a copy of the
  204.  *        local node's configuration ROM
  205.  * @bus_reset:    If non-zero, address of a buffer to be filled by a
  206.  *        &struct fw_cdev_event_bus_reset with the current state
  207.  *        of the bus.  This does not cause a bus reset to happen.
  208.  * @bus_reset_closure: Value of &closure in this and subsequent bus reset events
  209.  * @card:    The index of the card this device belongs to
  210.  */
  211. struct fw_cdev_get_info {
  212.     __u32 version;
  213.     __u32 rom_length;
  214.     __u64 rom;
  215.     __u64 bus_reset;
  216.     __u64 bus_reset_closure;
  217.     __u32 card;
  218. };
  219.  
  220. /**
  221.  * struct fw_cdev_send_request - Send an asynchronous request packet
  222.  * @tcode:    Transaction code of the request
  223.  * @length:    Length of outgoing payload, in bytes
  224.  * @offset:    48-bit offset at destination node
  225.  * @closure:    Passed back to userspace in the response event
  226.  * @data:    Userspace pointer to payload
  227.  * @generation:    The bus generation where packet is valid
  228.  *
  229.  * Send a request to the device.  This ioctl implements all outgoing requests.
  230.  * Both quadlet and block request specify the payload as a pointer to the data
  231.  * in the @data field.  Once the transaction completes, the kernel writes an
  232.  * &fw_cdev_event_request event back.  The @closure field is passed back to
  233.  * user space in the response event.
  234.  */
  235. struct fw_cdev_send_request {
  236.     __u32 tcode;
  237.     __u32 length;
  238.     __u64 offset;
  239.     __u64 closure;
  240.     __u64 data;
  241.     __u32 generation;
  242. };
  243.  
  244. /**
  245.  * struct fw_cdev_send_response - Send an asynchronous response packet
  246.  * @rcode:    Response code as determined by the userspace handler
  247.  * @length:    Length of outgoing payload, in bytes
  248.  * @data:    Userspace pointer to payload
  249.  * @handle:    The handle from the &fw_cdev_event_request
  250.  *
  251.  * Send a response to an incoming request.  By setting up an address range using
  252.  * the %FW_CDEV_IOC_ALLOCATE ioctl, userspace can listen for incoming requests.  An
  253.  * incoming request will generate an %FW_CDEV_EVENT_REQUEST, and userspace must
  254.  * send a reply using this ioctl.  The event has a handle to the kernel-side
  255.  * pending transaction, which should be used with this ioctl.
  256.  */
  257. struct fw_cdev_send_response {
  258.     __u32 rcode;
  259.     __u32 length;
  260.     __u64 data;
  261.     __u32 handle;
  262. };
  263.  
  264. /**
  265.  * struct fw_cdev_allocate - Allocate a CSR address range
  266.  * @offset:    Start offset of the address range
  267.  * @closure:    To be passed back to userspace in request events
  268.  * @length:    Length of the address range, in bytes
  269.  * @handle:    Handle to the allocation, written by the kernel
  270.  *
  271.  * Allocate an address range in the 48-bit address space on the local node
  272.  * (the controller).  This allows userspace to listen for requests with an
  273.  * offset within that address range.  When the kernel receives a request
  274.  * within the range, an &fw_cdev_event_request event will be written back.
  275.  * The @closure field is passed back to userspace in the response event.
  276.  * The @handle field is an out parameter, returning a handle to the allocated
  277.  * range to be used for later deallocation of the range.
  278.  */
  279. struct fw_cdev_allocate {
  280.     __u64 offset;
  281.     __u64 closure;
  282.     __u32 length;
  283.     __u32 handle;
  284. };
  285.  
  286. /**
  287.  * struct fw_cdev_deallocate - Free an address range allocation
  288.  * @handle:    Handle to the address range, as returned by the kernel when the
  289.  *        range was allocated
  290.  */
  291. struct fw_cdev_deallocate {
  292.     __u32 handle;
  293. };
  294.  
  295. #define FW_CDEV_LONG_RESET    0
  296. #define FW_CDEV_SHORT_RESET    1
  297.  
  298. /**
  299.  * struct fw_cdev_initiate_bus_reset - Initiate a bus reset
  300.  * @type:    %FW_CDEV_SHORT_RESET or %FW_CDEV_LONG_RESET
  301.  *
  302.  * Initiate a bus reset for the bus this device is on.  The bus reset can be
  303.  * either the original (long) bus reset or the arbitrated (short) bus reset
  304.  * introduced in 1394a-2000.
  305.  */
  306. struct fw_cdev_initiate_bus_reset {
  307.     __u32 type;    /* FW_CDEV_SHORT_RESET or FW_CDEV_LONG_RESET */
  308. };
  309.  
  310. /**
  311.  * struct fw_cdev_add_descriptor - Add contents to the local node's config ROM
  312.  * @immediate:    If non-zero, immediate key to insert before pointer
  313.  * @key:    Upper 8 bits of root directory pointer
  314.  * @data:    Userspace pointer to contents of descriptor block
  315.  * @length:    Length of descriptor block data, in bytes
  316.  * @handle:    Handle to the descriptor, written by the kernel
  317.  *
  318.  * Add a descriptor block and optionally a preceding immediate key to the local
  319.  * node's configuration ROM.
  320.  *
  321.  * The @key field specifies the upper 8 bits of the descriptor root directory
  322.  * pointer and the @data and @length fields specify the contents. The @key
  323.  * should be of the form 0xXX000000. The offset part of the root directory entry
  324.  * will be filled in by the kernel.
  325.  *
  326.  * If not 0, the @immediate field specifies an immediate key which will be
  327.  * inserted before the root directory pointer.
  328.  *
  329.  * If successful, the kernel adds the descriptor and writes back a handle to the
  330.  * kernel-side object to be used for later removal of the descriptor block and
  331.  * immediate key.
  332.  */
  333. struct fw_cdev_add_descriptor {
  334.     __u32 immediate;
  335.     __u32 key;
  336.     __u64 data;
  337.     __u32 length;
  338.     __u32 handle;
  339. };
  340.  
  341. /**
  342.  * struct fw_cdev_remove_descriptor - Remove contents from the configuration ROM
  343.  * @handle:    Handle to the descriptor, as returned by the kernel when the
  344.  *        descriptor was added
  345.  *
  346.  * Remove a descriptor block and accompanying immediate key from the local
  347.  * node's configuration ROM.
  348.  */
  349. struct fw_cdev_remove_descriptor {
  350.     __u32 handle;
  351. };
  352.  
  353. #define FW_CDEV_ISO_CONTEXT_TRANSMIT    0
  354. #define FW_CDEV_ISO_CONTEXT_RECEIVE    1
  355.  
  356. /**
  357.  * struct fw_cdev_create_iso_context - Create a context for isochronous IO
  358.  * @type:    %FW_CDEV_ISO_CONTEXT_TRANSMIT or %FW_CDEV_ISO_CONTEXT_RECEIVE
  359.  * @header_size: Header size to strip for receive contexts
  360.  * @channel:    Channel to bind to
  361.  * @speed:    Speed to transmit at
  362.  * @closure:    To be returned in &fw_cdev_event_iso_interrupt
  363.  * @handle:    Handle to context, written back by kernel
  364.  *
  365.  * Prior to sending or receiving isochronous I/O, a context must be created.
  366.  * The context records information about the transmit or receive configuration
  367.  * and typically maps to an underlying hardware resource.  A context is set up
  368.  * for either sending or receiving.  It is bound to a specific isochronous
  369.  * channel.
  370.  *
  371.  * If a context was successfully created, the kernel writes back a handle to the
  372.  * context, which must be passed in for subsequent operations on that context.
  373.  */
  374. struct fw_cdev_create_iso_context {
  375.     __u32 type;
  376.     __u32 header_size;
  377.     __u32 channel;
  378.     __u32 speed;
  379.     __u64 closure;
  380.     __u32 handle;
  381. };
  382.  
  383. #define FW_CDEV_ISO_PAYLOAD_LENGTH(v)    (v)
  384. #define FW_CDEV_ISO_INTERRUPT        (1 << 16)
  385. #define FW_CDEV_ISO_SKIP        (1 << 17)
  386. #define FW_CDEV_ISO_SYNC        (1 << 17)
  387. #define FW_CDEV_ISO_TAG(v)        ((v) << 18)
  388. #define FW_CDEV_ISO_SY(v)        ((v) << 20)
  389. #define FW_CDEV_ISO_HEADER_LENGTH(v)    ((v) << 24)
  390.  
  391. /**
  392.  * struct fw_cdev_iso_packet - Isochronous packet
  393.  * @control:    Contains the header length (8 uppermost bits), the sy field
  394.  *        (4 bits), the tag field (2 bits), a sync flag (1 bit),
  395.  *        a skip flag (1 bit), an interrupt flag (1 bit), and the
  396.  *        payload length (16 lowermost bits)
  397.  * @header:    Header and payload
  398.  *
  399.  * &struct fw_cdev_iso_packet is used to describe isochronous packet queues.
  400.  *
  401.  * Use the FW_CDEV_ISO_ macros to fill in @control.  The sy and tag fields are
  402.  * specified by IEEE 1394a and IEC 61883.
  403.  *
  404.  * FIXME - finish this documentation
  405.  */
  406. struct fw_cdev_iso_packet {
  407.     __u32 control;
  408.     __u32 header[0];
  409. };
  410.  
  411. /**
  412.  * struct fw_cdev_queue_iso - Queue isochronous packets for I/O
  413.  * @packets:    Userspace pointer to packet data
  414.  * @data:    Pointer into mmap()'ed payload buffer
  415.  * @size:    Size of packet data in bytes
  416.  * @handle:    Isochronous context handle
  417.  *
  418.  * Queue a number of isochronous packets for reception or transmission.
  419.  * This ioctl takes a pointer to an array of &fw_cdev_iso_packet structs,
  420.  * which describe how to transmit from or receive into a contiguous region
  421.  * of a mmap()'ed payload buffer.  As part of the packet descriptors,
  422.  * a series of headers can be supplied, which will be prepended to the
  423.  * payload during DMA.
  424.  *
  425.  * The kernel may or may not queue all packets, but will write back updated
  426.  * values of the @packets, @data and @size fields, so the ioctl can be
  427.  * resubmitted easily.
  428.  */
  429. struct fw_cdev_queue_iso {
  430.     __u64 packets;
  431.     __u64 data;
  432.     __u32 size;
  433.     __u32 handle;
  434. };
  435.  
  436. #define FW_CDEV_ISO_CONTEXT_MATCH_TAG0         1
  437. #define FW_CDEV_ISO_CONTEXT_MATCH_TAG1         2
  438. #define FW_CDEV_ISO_CONTEXT_MATCH_TAG2         4
  439. #define FW_CDEV_ISO_CONTEXT_MATCH_TAG3         8
  440. #define FW_CDEV_ISO_CONTEXT_MATCH_ALL_TAGS    15
  441.  
  442. /**
  443.  * struct fw_cdev_start_iso - Start an isochronous transmission or reception
  444.  * @cycle:    Cycle in which to start I/O.  If @cycle is greater than or
  445.  *        equal to 0, the I/O will start on that cycle.
  446.  * @sync:    Determines the value to wait for for receive packets that have
  447.  *        the %FW_CDEV_ISO_SYNC bit set
  448.  * @tags:    Tag filter bit mask.  Only valid for isochronous reception.
  449.  *        Determines the tag values for which packets will be accepted.
  450.  *        Use FW_CDEV_ISO_CONTEXT_MATCH_ macros to set @tags.
  451.  * @handle:    Isochronous context handle within which to transmit or receive
  452.  */
  453. struct fw_cdev_start_iso {
  454.     __s32 cycle;
  455.     __u32 sync;
  456.     __u32 tags;
  457.     __u32 handle;
  458. };
  459.  
  460. /**
  461.  * struct fw_cdev_stop_iso - Stop an isochronous transmission or reception
  462.  * @handle:    Handle of isochronous context to stop
  463.  */
  464. struct fw_cdev_stop_iso {
  465.     __u32 handle;
  466. };
  467.  
  468. /**
  469.  * struct fw_cdev_get_cycle_timer - read cycle timer register
  470.  * @local_time:   system time, in microseconds since the Epoch
  471.  * @cycle_timer:  isochronous cycle timer, as per OHCI 1.1 clause 5.13
  472.  *
  473.  * The %FW_CDEV_IOC_GET_CYCLE_TIMER ioctl reads the isochronous cycle timer
  474.  * and also the system clock.  This allows to express the receive time of an
  475.  * isochronous packet as a system time with microsecond accuracy.
  476.  */
  477. struct fw_cdev_get_cycle_timer {
  478.     __u64 local_time;
  479.     __u32 cycle_timer;
  480. };
  481.  
  482. #endif /* _LINUX_FIREWIRE_CDEV_H */
  483.